<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
  <head>
    <link rel="stylesheet" href="myatca.css" />
    <title>My ATCA Welcome Page</title>
  </head>
  <body>
    <div class="helppages">
      <h1>Online Observing Logs</h1>
      <a onclick="welcomeClick('www.narrabri.atnf.csiro.au/myatca/help_pages/welcome_secure.html')">
	Back to the welcome page</a>
      <p>
	The Online Observing Logs available in My ATCA make it easy for an observer to log events as they
	happen, while automatically producing log entries for common events such as:
	<ul>
	  <li>RPFITS files opening</li>
	  <li>loading a schedule file</li>
	  <li>specifying an array configuration, or correlator configuration</li>
	</ul>
      </p>
      <p>
	To use the My ATCA online observing logs you must register for a My ATCA account, and login, as
	described <a onclick="welcomeClick('www.narrabri.atnf.csiro.au/myatca/help_pages/authentication.html')">
	  here</a>. Once you are logged in, you can go to the Online Observing Logs front page by selecting the
	'Observing Logs' tab on the left of the My ATCA page.

      </p>
      <h2>Starting a new log</h2>
      <p>
	On the observing logs front page, there is a set of entry boxes at the bottom surrounded with
	a frame labelled 'Create New Log'. To make a new log you need to supply a log name, and a
	project code. You may also give a more verbose description of the log in the 'Description' field.
	Due to the way the logging works, it is preferable to have a separate log for each project code,
	although it is not strictly necessary, and the reasons for this will be described later. Once
	you have specified the name, project code, and optional description, press the 'Create' button
	to make the log. At this point, if the log is created successfully, you will see a new entry
	above the creation fields with the title and project code you just supplied.
      </p>
      <h2>Viewing and Editing Log details</h2>
      <p>
	On the observing logs front page, you will see a list of logs that you can edit or view.
	The first time you go to the front page, you will see only those logs that you may edit,
	either because you created the log, or you were added as an editor by another user. The
	number of such logs is listed at the top of the dotted box to the right of the title.
      </p>
      <p>
	It is however possible to view (almost) any log that any other user has created. Since
	the online observing logs are meant to replicate the red book in the ATCA control room,
	we have decided to allow all registered users to view any log. To show all the logs that can
	be viewed, change the dropdown box labelled 'Show logs that are:' from 'Editable only' to
	'Editable or viewable'. At this point the number of logs
	that can be edited or viewed will be shown.
	To go back to viewing only those logs you can edit, change the dropdown box back to 'Editable only'.
      </p>
      <p>
	You can also restrict which logs are shown in other ways using the fields in the dotted box.
	If you want to display only those logs that have a particular project code attached, enter that
	project code (case-insensitive) into the text entry box labelled 'Show logs with project code:'
	and press <tt>Enter</tt>.
	To remove this restriction, empty the box and press <tt>Enter</tt>.
      </p>
      <p>
	To the left of each log entry, there is a small right-pointing triangle. To view the details
	of a log, click the triangle next to its title. From the table that appears, you will
	(if you are listed as an editor of the log) be able to change the log's title and description
	by clicking the appropriate 'Edit' button. When editing the title, you should press the
	<tt>Enter</tt> key to submit any changes you make. When editing the description, you will
	need to press the 'Submit' button instead. When editing either field, you can press the
	<tt>Escape</tt> key to cancel your changes and go keep the entry as it was before you pressed
	the 'Edit' button.
      </p>
      <p>
	At the bottom of the details table is listed the users that can edit the log. If you are
	one of the editors, you will also see a text box labelled 'Add' and an 'Add' button. If
	you want to add another My ATCA user as an editor of this log, you should enter their
	(case-insensitive) email here and press the 'Add' button. If the user is recognised, the
	email address should appear in the list of editors shortly after you press the button.
      </p>
      <p>
	To hide the details of a log, press the (now bottom-pointing) triangle to the left of the
	title again.
      </p>
      <h2>Loading a log</h2>
      <p>
	To load a log, either to edit it or just view it, press the 'Load' button next to the
	log title on the front page. The front page will then be replaced by the log viewing screen.
      </p>
      <p>
	At the top of the log viewing screen there is a pane showing the log's title and
	project code, along with the description if it was specified. The log options are shown
	as a set of checkboxes; if the log is not editable, then these checkboxes will not be
	active. Below the options are shown a list of all the users that can edit the log. Both
	the options and user list can be hidden by clicking on the 'Options' or 'Users' bars.
	There is also a red label that reads 'Back to log loading screen' at the top of the
	viewing screen. Clicking on this label will close the log and show the observing log
	front page.
      </p>
      <p>
	The log entries are shown as a series of coloured boxes. The yellow boxes show
	entries that were generated automatically by the log, while the blue boxes show
	entries that were made and edited by an editor. At the top of each entry is shown
	the UTC time that the entry was made, and for each manually-created entry the time that
	the entry was last edited is shown at the bottom-right.
      </p>
      <h2>Editing a log</h2>
      <p>
	It is important to remember that a log can only be edited and updated while one
	of the users that are able to edit the log is currently viewing the log in their
	browser. That means that if noone is viewing the log, then no automatic entries will
	be made! The user's web browser is the client that makes it possible for the log to
	recognise when an RPFITS file has been opened, or when the schedule file has been
	changed etc.; there is no server-side mechanism to automatically fill in a log for
	any specific project.
      </p>
      <h3>Automatic log entries</h3>
      <p>
	The log itself will automatically insert an entry when:
	<ul>
	  <li>a new RPFITS file has been opened</li>
	  <li>a new schedule file has been loaded into <tt>caobs</tt> (although it will not
	  detect if that schedule is reloaded)</li>
	  <li>the correlator configuration has changed</li>
	  <li>the array configuration has changed</li>
	</ul>
	It does this by periodically querying the ATCA MoniCA server. When the log detects
	one of the above events, a new yellow-coloured entry will appear
	as the last entry, and it will contain text describing what event has just occurred.
	Because the monitoring points associated with each event are not polled more than
	once every 30 seconds (usually), there may sometimes be delays between the event
	actually occurring and the automatic entry being generated.
      </p>
      <p>
	For most automatically generated entries, you will not be able to specify anything.
	If the event relates to the opening of an RPFITS file however, you will see a
	dropdown box that will initially be set to 'Data'. This dropdown box can be used to
	indicate what type of data is in the RPFITS file. Most observers will perform array
	calibration (delays, phases and amplitudes) at some point in their setup, and such
	calibration events will make reduction difficult if left unflagged. Generally, it is
	best if you close the RPFITS file after finishing array calibration so it can simply
	be left out of the reduction process. Using the log, you may mark an RPFITS file as
	containing array calibration data by changing the dropdown box from 'Data' to
	'Calibration'. Note that this will mark the entire file as being calibration data, so
	you should not use this indicator if there is any useful data in the file.
      </p>
      <p>
	If you don't want some of these events to generate automatic log entries, you may
	change the log options at the top of the log viewing screen. Under the 'Options'
	bar, you will see a number of checkboxes labelled:
	<ul>
	  <li>RPFITS Files</li>
	  <li>Corr Configs</li>
	  <li>Sched Files</li>
	  <li>Array Configs</li>
	</ul>
	If the checkbox next to these labels is selected, then the log will automatically
	generate entries for such events. If you don't want a change of schedule file to
	generate an entry (for example), deselect the checkbox next to the 'Sched Files'
	label.
      </p>
      <p>
	Automatic entry generation is usually also restricted to those events related to
	the project code specified in the log. This means you may view your log while another
	project is running and not have irrelevant RPFITS files and schedules listed in your
	log. The log filters such events by checking the project code that the current
	RPFITS file has, and if it does not match the specified code, it will not make an
	automatic entry. This does mean however that if you are taking over from another
	observer, the log will not begin making automatic entries until you have started
	your observations. If you would rather have the log make entries without checking
	which project code is being used at the moment, you should deselect the checkbox
	next to the option labelled 'Only for this project code' under the 'Options' bar
	at the top of the log viewing screen.
      </p>
      <h3>User generated log entries</h3>
      <p>
	At the bottom of the log viewing page there is a button labelled 'New Log Entry'.
	To make a new entry that can be edited, click this button. You will see a new
	blue-coloured entry appear at the bottom of the log. It will timestamped with
	the current UTC date and time in the top left corner.
      </p>
      <p>
	By default, this new entry will contain the text 'Click edit to edit me'. At
	the bottom left of the entry box you will see a link labelled 'edit'. To edit the
	entry you should click this link, at which point the main body of the entry will
	be replaced with a text entry box, and the 'edit' link will be replaced with two
	links labelled 'submit' and 'cancel'.
      </p>
      <p>
	You may edit the entry to include any text that you want. You may also use
	<a href="http://www.wikicreole.org" target="wikicreole">WikiCreole 1.0</a>
	formatting to markup your text as bold, italics etc. There is a link to the
	WikiCreole 1.0 cheatsheet at the top right of every editable entry.
      </p>
      <p>
	Once you have finished editing your entry, you should press the 'submit' link
	to finalise your changes. At this point the text entry box will be replaced
	with the correctly rendered text, and the 'last altered' time at the bottom-right
	of the entry box should change to the current time. If this doesn't happen, it
	means that there was a problem while communicating with the log database. In this
	rare event, you should press the 'submit' button again until it works.
      </p>
      <p>
	If you have mistakenly begun editing the box, you can press the 'cancel' link
	to stop editing and keep the previous contents.
      </p>
      <p>
	You may also change the behaviour of the log when you press the 'New Log Entry'
	button using the Preferences system. On the 'Preferences' tab you will
	see a tab labelled 'Observing Logs', and under this you will see a dropdown box
	labelled 'When I click the 'New Log Entry' button:'. There are three options
	that you may choose from:
	<ul>
	  <li>'Add a new entry': this is the default option. When the 'New Log Entry'
	    button is pressed, a new entry will be made that contains the text
	    'Click edit to edit me', and you will need to then press the 'edit' link
	    to begin editing.</li>
	  <li>'Add a new entry and begin editing immediately': when this option is
	    selected, the 'New Log Entry' button will make a new entry containing the
	    text 'delete this text and replace it with your own', and the new entry
	    will already be editable; the cursor will also be ready to start typing.</li>
	  <li>'Add a blank new entry and begin editing immediately': when this option
	    is selected, the 'New Log Entry' button will make a new entry containing
	    no text, the entry will already be editable, and the cursor will be ready
	    to start typing; select this option for the fastest log-editing experience.</li>
	</ul>
	The 'New Log Entry' button's behaviour will change immediately after you
	select an option in the preferences tab.
      </p>
      <h3>Deleting a log entry</h3>
      <p>
	In each entry box there will be a 'delete' link that can be used to delete
	the entry. When you press this link, the entry will be replaced by a thin
	box containing the text 'You deleted an entry here. Undelete it or remove this
	message'. The text 'Undelete it' and 'remove this message' will be coloured
	differently because they are links. You may delete multiple entries, and for
	each deletion, the entry will be replaced by this box.
      </p>
      <p>
	If you decide that you want to recover a particular entry, you should click
	the 'Undelete it' link, at which point the entry will be restored back to
	where it was.
      </p>
      <p>
	If you are certain that you do not want the entry back, click the 'remove
	this message' link, and this box will disappear. At this point, you will be
	unable to recover the deleted entry. You will also lose the ability to
	recover a deleted entry if you leave the log viewing screen.
      </p>
      <h3>Preventing further changes</h3>
      <p>
	You may stop the log from being edited further by deselecting the checkbox
	labelled 'Allow changes' in the 'Options' tab at the top of the viewing
	screen. When this checkbox is deselected, no automatic or user-generated
	entries will be allowed to be made, edited or deleted by any editors.
      </p>
      <p>
	This is however not a permanent block - any editor may simply reselect
	this checkbox at any time to make the log editable again.
      </p>
    </div>

  </body>
</html>
